home *** CD-ROM | disk | FTP | other *** search
/ MIDICraft's MIDINET CD-ROM / MIDICraft's MIDINET CD-ROM.iso / DOSUTILS / MIDIDIR.DOC < prev    next >
Text File  |  1997-03-15  |  10KB  |  263 lines
  1.         ******************************
  2.             MIDIDIR v1.4
  3.  
  4.            midi directory listing
  5.               by Guenter Nagler
  6.                 1996
  7.           (gnagler@ihm.tu-graz.ac.at)
  8.         ******************************
  9.  
  10. [0] FEATURES
  11.     + scans subdirectories for binary midi files
  12.     + guesses title of the midi files 
  13.     + shows directory, filename, title, file size, format and number of tracks
  14.     + filename mask using wildcards ? and * can be used
  15.     + search words (may contain wildcards ? and *) to find certain titles
  16.     + can add title to a midi file
  17.     + shows midi mode (GM, GS, XG)
  18.     + produce database importable text 
  19.     + karaoke titles have higher priorities
  20.     + try to filter bad titles (e.g. advertisement)
  21.  
  22. [1] BACKGROUND
  23. This program was not my idea. The idea came from a person on net that asked
  24. for a simple way to generate a midi listing of a midi archive.
  25. Some answers suggested using MSDOS command "dir /S" to get a list.
  26. When I posted a zip file containing some of my midi files I added a file listing
  27. as content to the article description. I manually edited the content and got
  28. unexpected positive reactions for this listing.
  29.  
  30. So I thought that there must be a better way than "dir /S" to get a more
  31. detailed listing ( short DOS filenames often do not help).
  32.  
  33. Therefore I started this project mididir that be a simply way to 
  34. 1. get a directory listing (possibly with information about the midi files).
  35. 2. set title of a midi file
  36.  
  37.  
  38. [2] FILES DESCRIPTION
  39.  
  40. MIDIDIR.EXE.........converter program
  41. MIDIDIR.DOC.........this file, showing usage of MIDIDIR.EXE
  42. MIDIIO.HPP..........header file for a c++ midi parser
  43. MIDIIO.CPP..........source code for a c++ midi parser
  44. MIDIDIR.CPP.........c++ source code for directory listing and adding title
  45. MIDIDIR.MAK.........make file for project
  46. MIDIDIR.CFG.........compiler options for make
  47. MIDIDIR.PRJ.........compiler project for Borland (tm) c++ compilers
  48. only MIDIDIR.EXE is required to run program
  49.  
  50. [3] COPYRIGHT
  51.  
  52. MIDIDIR (c) 1996 was created by Guenter Nagler.
  53.  
  54. MIDIDIR is free and may be used as you wish with this one exception:
  55.  
  56.     You may NOT charge any fee or derive any profit for distribution
  57.     of MIDIDIR.  Thus, you may NOT sell or bundle MIDIDIR with any
  58.     product in a retail environment (shareware disk distribution, CD-ROM,
  59.     etc.) without permission of the author.
  60.  
  61. You may give MIDIDIR to your friends, upload it to a BBS, or ftp it to
  62. another internet site, as long as you don't charge anything for it.
  63.  
  64. [4] DISCLAIMER
  65.  
  66. MIDIDIR was designed to handle 100% compatible midi files.
  67. It was tested with many files but I can not say if 
  68. each 100% midi compatible midi file can be correctly converted.
  69. So I give no guarantees of the results, especially with non 100% 
  70. compatible midi files.
  71. If you find a midi file that you think to be 100% compatible midi
  72. that is not correctly converted, please send a sample file to 
  73. gnagler@ihm.tu-graz.ac.at . 
  74.  
  75. Use MIDIDIR at your own risk.  Anything you do with MIDIDIR is your
  76. responsibility, and not the author's.  Any damage caused to any person,
  77. computer, software, hardware, company, or business by running MIDIDIR
  78. is your responsibility, and the author will not be liable.
  79.  
  80. If you don't understand these terms, or are not sure of something, or
  81. are afraid something bad might come of using MIDIDIR, don't  use  it!
  82. You are here forewarned.
  83.  
  84. [5] INSTALLATION
  85.  
  86. [MSDOS]
  87. Simply copy MIDIDIR.EXE in a directory that is in your path.
  88. When you start the program without arguments
  89.  
  90. [UNIX]
  91. compile sources with your C++ compiler (e.g. GNU Compiler g++):
  92.  
  93. g++ -o mididir mididir.cpp midiio.cpp
  94.  
  95. and run program
  96.  
  97. $ mididir -h
  98.  
  99. C:\> MIDIDIR -h
  100.  
  101. you should get the usage text (see next section)
  102.  
  103. [6] USAGE
  104.  
  105. usage: MIDIDIR [-addtitle "title"] [-search "words"] files ...
  106.  
  107. The parts in brackets [...] are optional.
  108.  
  109. The program MIDIDIR allows following option:
  110. -version          get program version
  111. -addtitle "title"     add title of a single file 
  112. -search "words"          list only midi files with title containing the words
  113. -database             produce database importable format
  114.  
  115. Warning:
  116.   option -addtitle modifies the original file!
  117.  
  118. Warning:
  119.   Only on MSDOS system filemasks and subdirectories are handled internally by
  120.   this program. Under Unix the shell handles filemasks and subdirectories, so
  121.   use this in following manner (Unix only):
  122.  
  123.   $ mididir *.mid */*.mid
  124.    
  125.   searches all files matching *.mid in current directory and subdirectories     
  126.   for rekursive directory listing (deep nested) use Unix command find to start
  127.   mididir for each matching file. See Unix manual "man find" for description.
  128.  
  129. Karaoke titles ("@T...") are prefered, because if a song contains lyrics
  130. it is more likely that the title is added correctly.
  131.  
  132. [8] SUGGESTIONS / COMMENTS / BUG REPORTS / QUESTIONS
  133.  
  134.          WWW:    http://hgiicm.tu-graz.ac.at/Cpub
  135.           contains all my dos/unix midi programs
  136.          EMAIL:  gnagler@ihm.tu-graz.ac.at
  137.  
  138. [9] USE
  139.  
  140. example:  get version of program
  141. > mididir -v
  142. mididir v1.0 by Günter Nagler (13 Aug 1996)
  143.  
  144. example:  get usage help
  145. > mididir -h
  146. usage: mididir [-addtitle "title"] [-search "words"] files ...
  147.  
  148.  
  149. example:  search all midi files in current directory or subdirectories
  150. > mididir
  151. BONJOVI\KEPFAITH.MID:    Keep The Faith (58 kb, format 1, 11 tracks)
  152. BONJOVI\ARMS.MID:    In These Arms (45 kb, format 1, 9 tracks)
  153. BONJOVI\BLAZE.MID:     (92 kb, format 1, 31 tracks)
  154. KARAOKE\LIKECHOP.KAR:    I Like Chopin (41 kb, format 1, 11 tracks)
  155.  
  156. Lets interpret this output:
  157. BONJOVI\          tells that the file is in subdirectory BONJOVI
  158. KEPFAITH.MID          is the name of the file
  159. Keep The Faith       is probably the title of the midi 
  160. 58 kb            This is the size of midi file in kilobytes
  161. format 1        This is the format of midi file (0, 1, 2)
  162. 11 tracks        There are 11 different midi tracks
  163.  
  164. Warning: There is no midi title defined in midi standard, so this is the
  165. first trackname or first text found in midi file. Usually this contains
  166. something like a title, but it is optional or could be used for other 
  167. information.
  168.  
  169. example:  search only karaoke files 
  170. > mididir *.kar
  171. KARAOKE\LIKECHOP.KAR:    I Like Chopin (41 kb, format 1, 11 tracks)
  172.  
  173. example: search only files containing word "faith" in title
  174. > mididir -s "faith"
  175. BONJOVI\KEPFAITH.MID:    Keep The Faith (58 kb, format 1, 11 tracks)
  176.  
  177. example: complex search for more words containing wildcards
  178. > mididir -s "k t?e f*th"
  179. BONJOVI\KEPFAITH.MID:    Keep The Faith (58 kb, format 1, 11 tracks)
  180.  
  181. letter case is ignored, so first word "k" is contained in "Keep"
  182. t?e matches "The", because ? can be any character
  183. f*th matches "Faith", because * can be any character combination (even empty)
  184.  
  185. example: give blaze.mid a new title
  186. > mididir -a "Blaze of Glory" bonjovi\blaze.mid
  187.  
  188. Warning: this will modify the original file, so backup it if original
  189. file is important!
  190.  
  191. example: test new title of blaze.mid
  192. C:> mididir blaze.mid
  193. BONJOVI\BLAZE.MID:    Blaze of Glory (92 kb, format 1, 31 tracks)
  194.  
  195. example: produce a database about midi files information
  196. c:> mididir -database *.mid *.kar > midilist.txt
  197.  
  198. The file midilist.txt will contain lines like:
  199. Filename;Title/Artist;Filesize;Format;Tracks;Error;Specialmode
  200. RUNAWAY.MID;BON JOVI - Runaway;40524;1;8;;
  201. ECLIPSE.KAR;Total Eclipse of the Heart;40023;1;21;; GS
  202. TOTALECL.MID;;48759;1;12;;
  203. ... and more
  204.  
  205. Each line describes a midi file and builds a database record.
  206. The ; characters are field separators. 
  207. Following fields are generated:
  208. Filename;Title/Artist;Filesize;Format;Tracks;Error;Specialmode
  209.     Filename (path, name, extension)
  210.     Title/Artist (optional title or artist)
  211.     Filesize (number of bytes)
  212.     Format (0, 1, 2)
  213.     Tracks (Number of midi tracks)
  214.     Error (optional error message)
  215.     Specialmode (optional GM, GS, XG if midi contains a midi reset sysex)
  216.  
  217. Start your database application (e.g. Excel, Access, Works, StarCalc ...) 
  218. and open/import the text file (field separator is semicolon ";"). Now you
  219. can sort by filename, title, filesize, version and other fields.
  220.  
  221. Warning:
  222.   The title often is missing or not recognizable, because midi file
  223.   format doesn't mark a certain text to be a title or artist information. 
  224.   Any text in the midi file could be the title or artist, often none of 
  225.   the text lines is a title/artist. This causes mididir sometimes to 
  226.   show wrong midi title.
  227.  
  228. Hints: to get all text information from the midi use
  229.    miditrk or midifind [8]
  230.  
  231. Warning: All files that do not appear to be standard midi format are
  232.   ignored. A message at end of program shows the number of ignored files.
  233.  
  234. example: mididir collects midi files automatically, ignoring non-midi files
  235. c:> mididir 
  236. BONJOVI\BLAZE.MID:    Blaze of Glory (92 kb, format 1, 31 tracks)
  237. Warning: 33 files ignored (they are not standard midi files)
  238.  
  239. Hint:  if the output of mididir is written to a file or printer ( > or >> )
  240. then the warning is printed on screen.
  241.  
  242. Hint:  mididir without arguments is same as "mididir *.*"
  243.  
  244. [7] CHANGES
  245. v1.0 to v1.1:
  246.   * updated midiio
  247.   * added recognition of sysex midi mode initialization
  248.      (GM=General Midi, GS=Roland General Midi, XG=Yamaha General Midi)
  249. v1.1 to v1.2:
  250.   * added option -database to write a database importable file 
  251.   * ignores certain words that usually do not contain title or artist (e.g. 
  252.     unreadable text, advertisement, URLs...)
  253.  
  254. v1.2 to v1.3:
  255.   * speeding up program by skipping all events that are behind a time limit.
  256.     All needed information (title, tracks, reset,...) usually are done near
  257.     beginning of midi tracks.
  258.   * trying to continue directory listing even if reading corrupt midi file.
  259.     
  260. v1.3 to v1.4:
  261.   * long filename support for DOS 7.0/Windows95
  262.   * warning when ignoring non-midi files 
  263.